home *** CD-ROM | disk | FTP | other *** search
/ The PC-SIG Library 10 / The PC-Sig Library - Shareware for the IBM PC and Compatibles (PC-SIG)(Tenth Edition Disks 1-2804)(1991).iso / PC_SIGCD / 04 / 1 / DISK0416.ZIP / ROFF4.DOC < prev    next >
Text File  |  1985-08-10  |  41KB  |  1,227 lines
  1. .so header.rof
  2. .he /    ROFF4 V1.61//Augest 3,1985    /
  3. .fo ///Page  #     /
  4. .in 9
  5. .rm 71
  6. .nf
  7.           ROFF4, V1.60                  ROFF4, V1.61
  8. .sp
  9.       by Ernest E. Bergmann          by Conrad Kwok
  10.       Physics, Building #16          20 3rd St.,Section M,
  11.       Lehigh University              Fairview Park,
  12.       Bethlehem, PA 18015            Hong Kong.
  13.  
  14.  
  15. .fi
  16. .NP
  17. ROFF4 is an expanded version of ROFF, based on the
  18. formatter in Kernighan and Plauger's book SOFTWARE TOOLS, is
  19. written in BDS C. Now it is adapted on IBM PC using Microsoft 
  20. C.  Some of the input files may
  21. be used to "set-up" the formatter for
  22. a particular style and for particular hardware.  It is
  23. possible to substitute keyboard input instead of files for
  24. educational and test purposes.
  25. .NP
  26. 95% of the code of ROFF4 V1.61 is the same as V1.60. The 
  27. changes include:
  28. .sp
  29. .in +4
  30. .ti -4
  31. (1)&Modification to run on IBM PC using Microsoft C V1.04 or 
  32. Lattice C V1.04. Most of the other C compiler should be able 
  33. to compile the program with minor modification.
  34. .sp
  35. .ti -4
  36. (2)&Implementation of macro commmand with paramters.
  37. .sp
  38. .ti -4
  39. (3)&Fixing some minor bugs.
  40. .sp
  41. .ti -4
  42. (4)&Allow changing of character size on the same line with 
  43. superscript and subscript.
  44. .br
  45. .in
  46. .NP
  47. ROFF was provided by Neal Somos for the public
  48. domain via the BDS 'C' Users' Group's volume, CUG -- "Just
  49. Like Mom's".  Some of this documentation started there as
  50. well.
  51. .NP
  52. This formatter contains features important for the
  53. preparation of technical manuscripts.  Special symbols or
  54. fonts that can be defined by or for the user can be produced
  55. (if the hardware is capable!).  Super and subscripts can be
  56. handled as well as backspace even for printers without
  57. reverse scrolling or backspacing hardware capabilities.
  58. However, the output device should recognize separately the
  59. <CR> and <LF> functions.  The Epson MX-80 with GRAFTRAX 80
  60. was used by the author for most of the development, however
  61. he also was able to use the video display of the Exidy
  62. Sorcerer, which has user definable graphics.  "Preprocessor"
  63. directives can be used to merge stock phrases, boiler plate,
  64. make macro definitions, automate numbering, and create
  65. diversions (for footnotes, table of contents, etc.)
  66. .NP
  67. To support the capabilities of WORDSTAR[tm by
  68. MicroPro] extended underlining, strikeout, and multiple
  69. strike capability are provided as well.
  70.  
  71. .br
  72. Sample calls:
  73. .br
  74. .sp
  75. A>roff4 filename1 filename2 filename3 +)
  76. .sp
  77. .in +8
  78. this would send the formatted version of these three
  79. files to the console and to the printer
  80. .sp 1
  81. .in
  82. .sc #
  83. A>roff4 filename1 +)&filename2
  84. .sp
  85. .in +8
  86. this would format filename1 and send it to the printer,
  87. console, and to filename2.
  88. .sp
  89. .in
  90. A>roff4 -s -f filename1 -b filename2 -f -m -r -d -i -g -*
  91. .sp
  92. .in +8
  93. The option, -s, causes the formatter to stop (pause)
  94. at the start of each page of output; the bell at the
  95. console is sounded (if it exists!) and the program
  96. waits until any key is pressed at the console.  It
  97. is essential for printers that are feed single sheets
  98. at a time!
  99. .br
  100. .in
  101. .NP
  102. I do not use the redirection output feature of DOS 2.0 or 
  103. higer because this feature is extremely slow (30 times slower) 
  104. and the output will contain some unwanted characters. Hence 
  105. the symbol '&' is used for specifying the output file name.
  106. .NP
  107. .sc
  108. An option that was not shown above, -o[page or range],
  109. is used to selectively generate output of ONLY certain
  110. pages.  It is useful to retype pages that got "eaten"
  111. by the printer (Henry Harpending's aptly put language).
  112. To retype only page 23, say, make the option: -o23
  113. To retype pages 23 through 29 use: -o23-29
  114. To retype pages 23 to the end use: -23-
  115. These options changes the values of the internal
  116. variables, FIRSTPAGE and LASTPAGE which originally
  117. have the values of 1 and 30000, respectively.  Normally
  118. this option would be placed early enough in the
  119. command line that no pages have been printed yet.
  120. .NP
  121. The option, -f, would introduce a formfeed (0CH)
  122. into the output stream (useful for placing blank
  123. pages, or aligning printer pages) where it appears;
  124. in this example, before the first page of output,
  125. and, again, at the very end of the output.
  126. .NP
  127. The option, -b,  turns on the "debug" flag so as to
  128. print out lots of diagnostics to the STDERR[console].
  129. Probably only useful for those who are trying to
  130. trace the operation of the formatter for elusive
  131. bugs". This option is usable only when DEBUGON is defined 
  132. during compilation. See the file "ROFF4.H"
  133. .NP
  134. The option, -m, causes a list of macro definitions
  135. to be typed to the console.  It is a useful tool for
  136. debugging complex macro packages where the 
  137. preprocessor's expansions are too subtle for humans.
  138. .NP
  139. The option, -d, causes a list of diversion files to
  140. be typed to the console.  Its main virtue is to
  141. remind the user what files are being generated and
  142. their approximate size.
  143. .NP
  144. The option, -i, causes a list of string insertions
  145. to be typed to the console.  Useful for macro writers,
  146. as was the -m, described above.  Also, for noting
  147. what are the settings of "standard substitutions",
  148. such as "today's date".
  149. .NP
  150. The option, -r, causes a list of number registers to
  151. be typed to the console.  Could be useful to find
  152. the number of footnotes, etc.
  153. .NP
  154. The option, -g, causes a glossary of defined
  155. translated characters to be printed on the output
  156. device.  It is useful to check the appearance of
  157. all special definable characters and to produce
  158. a "wall chart" of special characters available.
  159. .NP
  160. The default option, -*, (the * could be any
  161. unassigned option) means keyboard input (buffered
  162. line-by-line with a prompt with the character used in
  163. the option, here *).  Typing a control-Z indicates
  164. an end-of-file; the formatter will continue with the
  165. next named file.  It is intended as a learning aid
  166. since one can tryout "tricky" input such as
  167. equations.  As with standard CP/M, a control-P can
  168. be used to toggle the printer to display output
  169. that would normally be sent to the console; also,
  170. one can edit the keyboard input with the backspace
  171. key.
  172. .NP
  173. Using ROFF4, you can make nice printouts of a file,
  174. with as little or as much help from the program as you want,
  175. depending on the commands.  There are default values for all
  176. parameters, so if you don't put any commands in at all, your
  177. file will come out with filled, right-justified lines.  The
  178. default line-length is 60 characters; the default page-
  179. length is 66 lines per page.  "Filled lines" means that as
  180. many input words as possible are packed onto a line before
  181. it is printed; "non-filled" lines go through the formatter
  182. w/o rearrangement.  "Right-justified" simply means that
  183. spaces are added between words to make all the right margins
  184. line up nicely.  To set a parameter, use the appropriate
  185. commands below. All commands have the form of a period
  186. followed by two letters. A command line should have nothing
  187. on it but the command and its arguments (if any); any text
  188. would be lost. 
  189. .NP
  190. Extra space will separate text sentences.  The sentence
  191. is recognized by a trailing ':',';','!','?', or a '.'.  For
  192. the '.' there is the additional requirement that either two
  193. or more spaces must spaces must follow it, or that it is at the
  194. end of the source line.
  195. .NP
  196. A command argument can be either ABSOLUTE or RELATIVE : 
  197. .br
  198. .nf
  199. .sp
  200.  .in     5       sets the indent value to 5 spaces
  201.  .in     +5      sets the indent value to the CURRENT value+5
  202.  .ls     -1      sets the line spacing to the current value-1
  203. .fi
  204. .NP
  205. Also,  all commands have a minimum and maximum value
  206. that will weed out any odd command settings (like setting
  207. the line spacing to zero, for example. It won't let you do
  208. that, but it could be changed if you REALLY have a burning
  209. desire to do so).
  210. .NP
  211. Some commands cause a "break", which is noted in the
  212. table below.  Before such a command goes into effect, the
  213. current line of text is put out, whether it is completely
  214. filled or not. (this is what happens at the end of a
  215. paragraph, for example.)  A line beginning with spaces or a
  216. tab will cause a break, and will be indented by that many
  217. spaces (or tabs) regardless of the indent value at that time
  218. (this is a "temporary indent", which can also be set
  219. explicitly).  An all blank line also causes a break.  If you
  220. find that some lines that are indented strangely, and it's
  221. not obvious WHY, look at which commands are causing a break,
  222. and which aren't. For instance:
  223. .sp
  224. .nf
  225.  .fi
  226.  .ti 0
  227.  this is a line of text
  228.  .in 8
  229.                                         <- blank line
  230.  more text for the machine to play with
  231. .fi
  232. .NP
  233. At first glance it seems obvious that the line "this is a
  234. line of text" will be indented zero spaces, but it won't -
  235. it will be indented 8. The indent command does NOT cause a
  236. break (although the .ti does) so it will not cause the line
  237. to be put out before setting the indent value to 8.  Then,
  238. when the blank line is encountered, it will cause a break -
  239. and "this is a line of text" will be indented incorrectly.
  240. The above example will give the following lines.
  241. .sp
  242. .fi
  243. .ti +0
  244. this is a line of text
  245. .in +8
  246.  
  247. more text for the machine to play with
  248. .br
  249. .in
  250. .NP
  251. It is worthwhile considering placing a ".br", the
  252. break command, before each use of ".in"; should future
  253. versions of ROFFn have the break already part of the indent
  254. command?
  255. .NP
  256. Certain system variables are "stacked" to enable
  257. reversion to earlier environments instead of "hardcoded"
  258. defaults.  For example:
  259. .sp
  260. .nf
  261.  .ls 1
  262.   .
  263.   .
  264.  .ls
  265. .sp
  266. .fi
  267. The first command will produce single line spacing (which is
  268. the default, but which may have been set otherwise at the
  269. beginning of the manuscript).  The second command causes
  270. resumption of the original line spacing (either the default
  271. or whatever had been chosen previously).  Stacked variables
  272. include: linespacing, indent column, right margin,
  273. translation flag character, page length, top and bottom
  274. margin sizes, unexpandable space character, output width,
  275. tabsize, and control flag character.
  276. .nf
  277. .ne 6
  278. .sp
  279. *********************** Table of Commands *********************
  280.  
  281.  Command       Break?    Default stacked Function
  282.  -------       ------    ------- ------- ---------
  283.  .. string       no                      string is "mere"comment
  284.  
  285.  .ab             no                      immediate abort back to
  286.                                          system
  287.  
  288.  .bj             yes                     break with right
  289.                                          justification (current
  290.                                          line only)
  291.  
  292.  .bp n           yes     n =  +1         begin page numbered n
  293.  
  294.  .br             yes                     cause a break (this
  295.                                          line is not justified)
  296. .cf :
  297.  
  298.  .cf c           no      c = '^' Yes     to be used as a prefix
  299.                                          to a character that
  300.                                          controls print func-
  301.                                          tions such as ^+,^-
  302.                                          might be used to
  303.                                          bracket superscripts,
  304.                                          somewhat like
  305.                                          WORDSTAR(TM).
  306. .cf ^
  307.  
  308.  .ce n           yes     n = 1           center next n lines
  309.  
  310.  .db n           no      n = 0(NO)       set debug flag 1 for
  311.                                          diagnostics
  312.  
  313.  .di name        no      JUNK.$$$        diversion file
  314.                                          (see "PREPROCESSOR")
  315.  
  316.  .dm name        no                      define (multiline)
  317.                                          macro ("PREPROCESSOR")
  318.  
  319.  .ds /../../../  no      null string     define string replace-
  320.                                           ment ("PREPROCESSOR")
  321.  
  322.  .ed             no                      end diversion
  323.                                          (see "PREPROCESSOR")
  324.  
  325.  .ef /../../../  no      blanks          even footer titling
  326.  
  327.  .eh /../../../  no      blanks          even header titling
  328.  
  329.  .em                                     end macro
  330.                                          (see "PREPROCESSOR")
  331.  
  332.  .fi             yes                     start filling lines
  333.  
  334.  .ff n           no      n = 1(yes)      initially, formfeeds
  335.                                          are "off". Can turn
  336.                                          them on.  Each page
  337.                                          then terminated with
  338.                                          one formfeed.
  339.  
  340.  .fo /../../../  no      empty           sets both even and odd
  341.                                          page footers
  342.  
  343.  .fr # base - ;  no      1,no action     defines how to put
  344.  - - - - .                               output device in mode
  345.                                          for fractional line
  346.                                          spacing(for super,sub-
  347.                                          scripting);see details
  348.                                          given below. Comple-
  349.                                          ments .WH, below.
  350.  
  351.  .he /../../../  no      empty           sets both even and odd
  352.                                          page headers
  353.  
  354. .ic /
  355.  .ic c           no      c = '\' Yes?    to specify the char-
  356.                                          acter used for macro
  357.                                          preprocessing to denote
  358.                                          the token that follows.
  359. .ic \
  360.  
  361.  .ig string      no                      "ignore" string(see ..)
  362.  
  363.  .in n           no      n = 10  Yes     set indent value to n
  364.  
  365.  .ju             no      initially on    turn on right justifi-
  366.                                          cation (only applicable
  367.                                          if "filling" also)
  368.  
  369.  .ls n           no      n = 1   Yes     set line spacing to n
  370.  
  371.  .m1             no      n = 2   Yes     set topmost margin to n
  372.  
  373.  .m2             no      n = 2   Yes     set 2nd top margin to n
  374.                                          lines
  375.  
  376.  .m3             no      n = 2   Yes     1st bottom margin to n
  377.                                          lines
  378.  
  379.  .m4             no      n = 2   Yes     bottom-most margin to n
  380.                                          lines
  381.  
  382.  .ne n           no/yes  n = 2           "need" n lines; if have
  383.                                          them no action; else
  384.                                          begins new page
  385.  
  386.  .nf             yes                     stop filling lines
  387.  
  388.  .nj             no      initially       turn off right justi-
  389.                          is justifying   fication (only relevent
  390.                                          if "filling" also)
  391.  
  392.  .of /../../../  no      empty           odd page footer title
  393.  
  394.  .oh /../../../  no      empty           odd page header title
  395.  
  396.  .ou base - - ;  no      not applicable  direct output of code
  397.  - - - .                                 sequences to output.
  398.  
  399. .ne 2
  400.  .ow             no      n = 80          sets output width for
  401.                                          header and footer title
  402.  
  403.  .pc c base - ;  no      not applicable  used to create
  404.  - - - .                                 definitions for special
  405.                                          printer controls, such
  406.                                          as for italics.
  407.  
  408.  .pl n           no      n = 66  Yes     sets page length to n
  409.  
  410.  .rg name n      no      n=0     No      create or modify 
  411.                                          register variable
  412.                                          (see "PREPROCESSOR")
  413.  
  414.  .rm n           no      n = 70  Yes     sets right margin to n
  415.  
  416.  .sa string                              "say": message to
  417.                                          console; like a comment
  418.                                          but displayed to
  419.                                          operator during run.
  420.  
  421.  .sc c           no      blank   Yes     space character; the
  422.                                          visible character
  423.                                          that will be trans-
  424.                                          literated to unexpanded
  425.                                          blank.
  426.  
  427.  .so filename    no      ignored Yes     reads named file into
  428.                                          input stream; cannot be
  429.                                          invoked from keyboard
  430.                                          input.
  431.  
  432.  .sp n           yes     n = 1           space down n lines
  433.  
  434.  .st n           no      n=1(yes)        stop(pause)at each page
  435.                                          start; initially off;
  436.                                          may also be enabled by
  437.                                          the -s option.
  438.  
  439. .tc %
  440.  .tc c           no      ~       Yes     set translation flag
  441.                                          character, see .tr
  442. .tc ~
  443.  
  444.  .tr c base - ;  no      not applicable  used to create
  445.  - - - .                                 definitions for special
  446.                                          character fonts.
  447.  
  448.  .ts n           no      n = 8   Yes     sets value of tab space
  449.  
  450.  .ti n           yes     n = 0           set temp. indent of n
  451.  
  452.  .wh             no      no action       instructs how to resume
  453.                                          whole line spacing;
  454.                                          complements .FR, above.
  455.  
  456.   -------------------------------------------------------------
  457. .ne 27
  458. .sp 2
  459. Here's what the page parameters look like:
  460.  
  461.         |<--------output width (.ow)------------------->|
  462.  
  463. _       _________________________________________________
  464. |       |       top margin(m1) - (includes header)      |
  465. |       |-----------------------------------------------|
  466. |       |               top margin 2                    |
  467. |       |-----------------------------------------------|
  468. P       |       :                               :       |
  469. A       |       :<-indent                       :       |
  470. G       |       :                               :       |
  471. E       |       :lots and lots of silly text and:       |
  472. L       |       :other garbage. Get the picture?:       |
  473. E       |          :This is a temp.  indentation:       |
  474. N       |       :                               :       |
  475. G       |       :               right margin -> :       |
  476. T       |       :                               :       |
  477. H       |       :                               :       |
  478. |       |-----------------------------------------------|
  479. |       |               margin 3                        |
  480. |       |-----------------------------------------------|
  481. |       |  margin 4 - (includes footer,perhaps ff)      |
  482. -       -------------------------------------------------
  483.  
  484. .fi
  485. Minimum acceptable values for M1, M2, M3, and M4; if M1 is set
  486. to zero, no header will be shown (even if one was declared).
  487. Similarly, if M4 is set to zero, no footer will be displayed.
  488. .NP
  489. To change the default for any parameter, simply alter ROFF4.H
  490. and reExecute COMPILE.BAT.
  491.  
  492. .nf
  493. ************************************************************
  494. A Few Extra Comments on Some of the Commands:
  495. ************************************************************
  496. .NP
  497. If you want to center lots of lines, but don't
  498. want to count them, do something like this:
  499. .sp
  500. .nf
  501.  .ce     1000
  502.  lots and
  503.  lots of words to
  504.  be centered
  505.  .ce 0
  506. .sp
  507. will give the lines:
  508. .ce 1000
  509. lots and
  510. lots of words to
  511. be centered
  512. .ce 0
  513. .sp
  514.         --------------------------------------
  515. .fi
  516. .sp
  517. .NP
  518. A new paragraph may be caused by using the temporary indent
  519. command, like
  520. .sp
  521. .nf
  522.  .ti +5
  523. .fi
  524. .sp   
  525. or by simply beginning the paragraph with a tab, as you would
  526. if you were just typing.
  527.  
  528.         ------------------------------------
  529.  
  530. .NP
  531. For special cases, where you wish to place the last
  532. "word" at the right-hand margin, such as numbers of equation,
  533. for example:
  534. .br
  535. .sc #
  536. # x#=#y+z (12)
  537. .bj
  538. you could input:
  539. .sc &
  540. .br
  541. .nf
  542. .in -1
  543.  # x#=#y+z (12)
  544.  .bj
  545. .in
  546. .fi
  547. because we force a break with justification (.bj) of the
  548. line with only "three words". (The # is assumed to be the
  549. "space character" set up with a .sc command).
  550.  
  551.         ------------------------------------
  552.  
  553. .ce 1
  554. Headers and Footers.
  555. .NP
  556. A page number can be incorporated into any header or
  557. footer by putting a "#" in the title where you want the number
  558. to go:
  559. .nf
  560.  .he     /This is a witty header title for page #/
  561. .fi
  562. Each time this is printed at the top of a page, the current
  563. page number will be substituted for the "#".
  564. Each footer and header are ".in 0", even if text is
  565. indented.
  566. .NP
  567. Headers and footers are in three parts.  These parts are left
  568. justified, centered, and right justifed.  Any of these three
  569. parts may be left out.  The right justification is fixed to the
  570. margin that is set by the .OW command.  One may pick the
  571. headers and footers separately for even and odd pages.  For
  572. example, one could place even and odd page numbers at the
  573. bottom outside of each page by:
  574. .nf
  575.  .ef /Page #///
  576.  .of ///Page #/
  577.  
  578. .fi
  579. .NP
  580. .ic %
  581. Any printable character, here the '/', can be used to
  582. delimit the three strings that make up the titles, so long
  583. as it is not the "insert character" (usually, '\') and is
  584. not present in any of the three strings.
  585. .ic \
  586. .NP
  587. The program can be made to wait for the operator to
  588. load single sheets of paper by the -s option and/or by the
  589. command: .st
  590.  
  591.         ------------------------------------
  592. .NP
  593. If you want to send the output to a file, and don't want the
  594. page breaks in there set margins 1-4 to zero.
  595.  
  596.         ------------------------------------
  597. .NP
  598. Where you need to supply code sequences for
  599. immediate or for subsequent output (for .ou or for .tr) one
  600. needs to supply the number base (binary, octal, decimal, or
  601. hexadecimal) by supplying a token that begins with (upper
  602. and lowercase are both o.k.): b, o(or q), d, or h. Following
  603. the base on the same and/or subsequent lines one supplies
  604. the codes that will form the "code string". These codes are
  605. delimited by white space (not commas!) and the sequence is
  606. eventually terminated by a token beginning with a period.
  607. The ends of any of these lines may contain comments if they
  608. are set off by white space and a semicolon. For examples:
  609. .nf
  610.  .ou hex 11 1C 8C 0
  611.  99 6C 55 ;get ready!
  612.  .end
  613.  
  614.  .TR = binary ;"identity"operator (triple equal sign) on MX-80
  615.  00011011 ;ESC
  616.  01001011 ;4B
  617.  00000110 ;6 bit patterns
  618.  0        ;follow:
  619.  00101010 ;left top,bot
  620.  00101010
  621.  00101010
  622.  00101010
  623.  00101010
  624.  00000000 ;right top,bot
  625.  .en
  626. .fi
  627. .NP
  628. The first of these examples might be used to get
  629. some strange printer to cooperate in standing on its head or
  630. something.  
  631. .NP
  632. .tc %
  633. The second, lengthier example is taken from a file,
  634. MX, that defined quite a number of special characters for
  635. the MX-80 with GRAFTRAX 80.  Because that printer uses dot
  636. graphics, I chose to make the definition in binary so that
  637. the placement of the individual dots is easier to visualize.
  638. Later, in the text the combination: ~=  will cause the
  639. printer to be sent this code so that it will print the
  640. specialized symbol.
  641. .sp 2
  642. .tc
  643.                       SPECIAL SYMBOLS
  644. .NP
  645. If one includes a set of definitions such as in the
  646. MX file, one can specify the use of special symbols, which
  647. can be chosen to fit the application (and the hardware!) For
  648. example, the MX-80 printer equipped with GRAFTRAX 80 can
  649. accept dot addressed graphics.  [See the MX file for
  650. examples with this hardware].  Other printers may be able to
  651. simulate symbols by a combination of overstruck characters.
  652. Still other output devices may be capable of displaying
  653. desired special symbols by use of the "parity bit".
  654. .NP
  655. The .tr and .tc commands define the codes for the
  656. special symbols and the translation character.  To create a
  657. "wall chart" that lists the special characters on the output
  658. device you could use the -g option on the command line, for
  659. example:
  660. .nf
  661. A>roff4 mx -g )
  662.  
  663.  
  664. .ce 1
  665. ====================================
  666.  
  667.  
  668. .ce 1
  669. PRINTER CONTROL
  670. .fi
  671. .NP
  672. It is assumed that the output device can accept
  673. carriage returns and will not linefeed in the absence of the
  674. linefeed character.  Using this assumption, super- and
  675. subscripting, backspacing, underscoring, strickout, and
  676. multiple impressions are supported in a manner somewhat
  677. analogous to WORDSTAR [tm by MicroPro], but more generally.
  678. .NP
  679. If the printer can be placed in fractional
  680. linespacing mode, so much the better, as full line spacing
  681. for super- and subscripts does not look as "natural".  Also,
  682. with the half line spacing, one can build up larger
  683. characters (such as summation and integration symbols) since
  684. some overlap does occur.  To implement such fractional
  685. spacing one uses the commands, .fr and .wh (probably at the
  686. beginning of the input file, along with other information
  687. relevent to the output device and style).  These commands
  688. describe the operational codes sent to the output to switch
  689. the printer to FRactional spacing and back to WHole line
  690. spacing.
  691. .NP
  692. For example,  I use for the MX-80 printer equipped
  693. with GRAFTRAX 80 the following:
  694. .nf
  695. .sp
  696.  .WH HEX 1B 32 . ; 6 lines/inch is standard
  697.  .fr 2 hex 1b 33 12 . ; 18/216" = halfline spacing
  698. .fi
  699. .sp
  700. The initial 2 in .fr tells the formattter that 2 fractional
  701. [half] lines are equivalent to a conventional whole line.
  702. The original description of the required codes were in
  703. hexadecimal, so I kept matters as simple as possible by
  704. using the same number base so that I would not make any
  705. conversion mistakes!
  706. .NP
  707. .cf $
  708. The printer control requests are embedded in the
  709. text; they are NOT set off in separate lines as the "dot"
  710. commands are set apart.  Each request is made up of two
  711. printable characters, the first of which is the "control
  712. flag character" (the default is '^').  Here is a table of
  713. control functions presently supported by ROFF4, version 1.30:
  714. (additional codes can be created with the "printer control"
  715. command, .pc)
  716. .sp 2
  717. .in +8
  718. .ti -8
  719. ^+&&&&&&up a fractional line; may be used several times to
  720. increase vertical rise. [used at start of a
  721. superscript and at the end of a subscript]
  722. .sp
  723. .ti -8
  724. ^-&&&&&&down a fractional line; may be used several times to
  725. increase vertical drop. [used at the start of a
  726. subscript and at the end of a superscript]
  727. .sp
  728. .ti -8
  729. ^h,^H&&&backspace one character column.  Do NOT backspace
  730. over ordinary blanks ("unexpandable" space is o.k.)
  731. if you are in "fill" mode.
  732. .sp
  733. .in
  734. .nf
  735. ^(,^)   Note current column position; return to noted position.
  736. ^[,^]   "       "       "       "       "       "       "
  737. ^{,^}   "       "       "       "       "       "       "
  738. .fi
  739. .in +8
  740. .sp
  741. The above three pairs of controls are often more
  742. convenient then multiple, explicit backspaces, ^H,
  743. especially for "built-up" fractions and matrices.
  744. .sp
  745. .ti -8
  746. ^B,^b&&&Start, end boldface (increase, decrease the number
  747. of impressions by a factor of 3).
  748. .sp
  749. .ti -8
  750. ^D,^d&&&Start, end doublestrike (increase, decrease the number
  751. of impressions by a factor of 2).
  752. .sp
  753. .ti -8
  754. ^U,^u&&&Start, end underscore (will not underscore
  755. expandable white space; will ride up and down with
  756. super and subscripts.)
  757. .sp
  758. .ti -8
  759. ^X,^x&&&Start, end strikeout (similar to underscore, above,
  760. but overprints with '-' instead of underlines).
  761. .sp
  762. .in
  763. .NP
  764. Note that the last 4 pairs are "case sensitive";
  765. namely, the uppercase starts some activity, whereas the
  766. lowercase equivalent sqelches it;  these controls are
  767. NOT "toggles".
  768. .NP
  769. An involved example of the use of printer controls
  770. would be to create a 3 by 3 matrix:
  771. .sp
  772. MATRIX =#^+^+^(|1#2#3|^)^-^-|4#5#6|^)^-^-|7#8#9|^+^+
  773.  
  774. which should produce (with a half-spacing) printer:
  775.  
  776. .nf
  777.          |1 2 3|
  778. MATRIX = |4 5 6|
  779.          |7 8 9|
  780.  
  781. .fi
  782. [the demonstration file, MATRIX, has been provided as a
  783. demonstration of the above].
  784. .NP
  785. Several points should be observed.  There should be no
  786. expandable blank spaces if you are in fill mode, otherwise,
  787. the result might be very strange! (ROFF4 does some checks to
  788. flag such attempts). We are assuming here that the '#' are
  789. unexpandable spaces (chosen with the .sc command).  The
  790. first printable character in the complex, the '=', is at the
  791. leftmost edge; the last printable character, the '|'
  792. following the '9', is at the rightmost edge of this
  793. assemblage.  The final height is adjusted (by the trailing
  794. ^+^+ ) to match the initial height.  The present limit of
  795. the line buffering is 255 characters; I assume that is not
  796. too chancy.
  797. .NP
  798. One can define additional printer control codes
  799. using the .pc command.  For example, the MX-80 printer with
  800. Graftrax is switched to italics with the sequence <ESC> '4';
  801. and italics are turned off with <ESC> '5'.  We could define
  802. ^I to start italics and ^i to end them:
  803. .nf
  804. .sp
  805.  .pc I hex ;italics on (MX-80 & Graftrax)
  806.  1B 34
  807.  .en
  808.  .pc i hex ; italics off (MX-80 & Graftrax)
  809.  1B 35
  810.  .en
  811. .sp 2
  812. .cf
  813.               ================================
  814.  
  815. .ce 1
  816. THE PREPROCESSOR
  817. .fi
  818. .ic %
  819. .NP
  820. In the following we describe the advanced macro
  821. preprocessing features of this formatter which provide users
  822. with labor saving tools but which are probably not necessary
  823. at first.  The beginning user may be able to achieve most
  824. goals without the "preprocessing", but by using an editor
  825. more then otherwise.  The more advanced user will begin to
  826. appreciate these features more.
  827. .NP
  828. In the following discussion we will assume the
  829. default insert character, '\', and the default command
  830. character, '.', will be used.  (It is rare that you should
  831. change these anyway!)
  832. .NP
  833. The insert character is used to denote where a
  834. replacement should be used.  For example, in:
  835. .sp
  836. Today, \date\, is special.
  837. .sp
  838. the block, "\date\", would be replaced as this sentence is
  839. being input.  If a prior string definition of the form:
  840.  
  841.  .ds *date*January 1, 1983*
  842. .ds *date*January 1, 1983*
  843.  
  844. had been processed previously then the example, after text
  845. substitution, would become:
  846.  
  847. .ic \
  848. Today, \date\, is special.
  849. .ic %
  850. .br
  851. .NP
  852. The string definition command, .ds, expects that the
  853. first visible character, here a '*', is the delimiter of the
  854. start and end ot the two parts in the definition;  any
  855. printable character (that is not present in either string!)
  856. may be used.
  857. .NP
  858. If no string definition had been provided for "date", the
  859. user will be prompted while the formatter is trying to input
  860. this sample line.  The console will get some message like:
  861.  
  862. [Bell]Please define <date>:
  863. .NP
  864. Whatever you type in will be used to form an "effective" .ds
  865. definition.  This feature should be useful in applications
  866. where information should be changed or updated each time the
  867. formatter is run, such as today's date, the addressee's name
  868. and address in a form letter, etc.  A sample file, FORM is
  869. included to demonstrate both of the above means to define
  870. string substitutions.
  871. .NP
  872. An important restriction must be observed when using
  873. "definitions on the run".  They must not be first used
  874. inside of multiline definitions (namely inside of .ou, .tr,
  875.  .dm, .pc, .wh, and .fr) because the building of both
  876. definitions will cause them to interfere with each other.
  877. ROFF4, v1.6 will test for such contention and abort
  878. operation if one is found.  An example of such a situation
  879. and its remedy is shown below:
  880. .nf
  881.  .sa chose 0 for DRAFT and 1 for CORRESPONDENCE
  882.  .ou hex
  883.  1B
  884.  3\font\
  885.  .end .ou
  886. .fi
  887. .NP 
  888. This example, which might be used to initialize the Okidata
  889. Microline 92 printer to go into correspondence quality or
  890. into draft quality printing would cause problems if "font"
  891. is supposed to be defined here during execution.  We are in
  892. the midst of defining an output string for the printer (ESC
  893. "0" or ESC "1") when we are asking ROFF4 to create
  894. (simultaneously) a definition for "font";  the program will
  895. abort rather than continue with the two definitions mangling
  896. each other.  Here is a modified version of above without the
  897. problem:
  898. .sp
  899. .nf
  900.  .sa chose 0 for DRAFT and 1 for CORRESPONDENCE
  901.  .. this comment containing \font\ is "ignored"
  902.  .ou hex
  903.  1B
  904.  3\font\
  905.  .end .ou
  906. .fi
  907. .NP
  908. The fix here is that the formatter will encounter "\font\"
  909. in the comment and complete a definition for "font" before
  910. takling the .ou command;  no simultaneous definitions, no
  911. problems!
  912. .NP
  913. Similar to string definitions are register
  914. variables, which are created and modified with the .rg
  915. command.  Variables are useful for enumeration such as
  916. equation numbering:
  917.  
  918.  .rg eqnum 1
  919. .rg eqnum 1
  920.  
  921. would create a register named "eqnum" with the current value
  922. of 1.  The the text might use it with, say:
  923.  
  924.          x = y+1          (\eqnum\)
  925.  
  926. which would be converted on input into:
  927.  
  928. .ic \
  929.          x = y+1          (\eqnum\)
  930. .ic %
  931.  
  932. A subsequent instruction:
  933.  
  934.  .rg eqnum +1
  935. .rg eqnum +1
  936.  
  937. would take the current value of "eqnum" and increase it by 1
  938. (so that it would now be 2 in our example:
  939.  
  940.          a = b+c          (\eqnum\)
  941.  
  942. would become:
  943.  
  944. .ic \
  945.          a = b+c          (\eqnum\)
  946. .ic %
  947. .NP
  948. There is a special, reserved insertion, \#\, which
  949. will provide the current page number.  It should prove
  950. useful in setting up tables of contents (see "diversions",
  951. below).  Trivial examples of its use are to be found in the
  952. files, BPTEST and MARGINS.  In rare cases it may be off one
  953. page because it may be read while between pages;  how can one
  954. handle the sentence, "This sentence is on page XXX," when the
  955. sentence straddles two pages?
  956. .NP
  957. Since we have defined a special register name, '#',
  958. we should comment on what happens if you create a register
  959. instruction with that name, such as:
  960.  
  961.  .rg # +1
  962.  
  963. You will be changing the value of the page number of the
  964. FOLLOWING pages.  This is useful for leaving gaps in the 
  965. pagination for later inclusion of full page illustrations.
  966. This feature is demonstrated (tested) in the file, MARGINS.
  967. I wish to thank Henry Harpending for suggesting this.
  968. .NP
  969. The insert character has other properties.  The
  970. insert character can be placed into the input by repeating
  971. it, namely, "\\" becomes "\".  (useful for delaying
  972. substitutions).  For example, defining:
  973.  
  974.  .ds 'EN'(\\eqnum\\)'
  975.  
  976. will identify "EN" with "(\eqnum\)" and so our equation
  977. example above could have been:
  978.  
  979.          a = b+c          \EN\
  980.  
  981. Delaying the evaluation of "eqnum" until EN is invoked
  982. (instead of when it was defined) means that the proper
  983. numbering of equations will occur instead of wrongly
  984. supplying the value of "eqnum" from the time that EN was
  985. first created.
  986. .NP
  987. If the insert character is at the end of a line, it
  988. negates the following newline sequence;  thus the next line
  989. is merged with the current line.  For example:
  990.  
  991. .nf
  992. antidisestab\
  993. lishmentarianism
  994. .fi
  995.  
  996. is equivalent to:
  997.  
  998. .ic \
  999. antidisestab\
  1000. lishmentarianism
  1001. .ic %
  1002. .NP
  1003. "Macro" definitions are used when we wish to
  1004. identify several lines with an insertion.  Such definitions
  1005. are created with the .dm ["define macro"] and completed with
  1006. the .em ["end macro"] commands.  For example, we might wish
  1007. to use the following sequence over and over again at the
  1008. start of paragraphs:
  1009. .sp
  1010. .nf
  1011.  .sp 1
  1012.  .ne 2
  1013.  .ti +5
  1014. .fi
  1015. .NP
  1016. to separate the paragraphs by blank lines, keep them from
  1017. starting excessively close to the bottom of the page, and
  1018. indenting them 5 spaces to the right of the current left
  1019. margin.  We might want to define the "command" as
  1020. "paragraph" [personally, I might call it "P", because it
  1021. would be used a lot and my typing ...]:
  1022. .nf
  1023. .sp
  1024.  .dm paragraph
  1025.  .sp 1
  1026.  .ne 2
  1027.  .ti +5
  1028.  .em
  1029. .fi
  1030. .NP
  1031. Subsequently, whenever we wished to start a paragraph we
  1032. would creat a command line:
  1033.  
  1034.  .paragraph
  1035.  
  1036. instead of more tediously creating every time the three
  1037. commands we mentioned above.
  1038. .NP
  1039. The names of all macros, strings, and number
  1040. registers are "case sensitive".  That is to say that
  1041. capitalization and/or lower case are distinguished and, say,
  1042.  
  1043.  .Paragraph
  1044.  
  1045. Would not be recognized as the same as the sample macro we
  1046. just defined.  However, all the "built-in" commands, those
  1047. which were listed in the command table, are not case
  1048. sensitive and are recognized on the first two letters alone,
  1049. even if arbitrary letters or numbers follow immediately.
  1050. If we had a line:
  1051.  
  1052.  .time
  1053.  
  1054. it would be identified with a "time" macro definition, if
  1055. one had been created;  It would not be confused with a
  1056. "Time" macro definition.  If there is no "time" macro, then
  1057. it would be matched with the "built-in", .TI ["temporary
  1058. indent"].
  1059. .NP
  1060. A macro command may contain parameters(s). For example
  1061.  
  1062. .cf !
  1063. .nf
  1064.  .dm HEADING
  1065.  .sp 2
  1066.  ^B$0^b
  1067.  .sp 2
  1068.  .em
  1069. .cf ^
  1070. .dm HEADING
  1071. .sp 2
  1072. ^B$0^b
  1073. .sp 2
  1074. .em
  1075. .fi
  1076. defines a macro for printing heading. When the line ".HEADING 
  1077. Heading" appear on the beginning of a line, the word "Heading" 
  1078. will be printed in boldface with two blank lines above and 
  1079. below. i.e.
  1080. .br
  1081. .HEADING Heading
  1082. .cf
  1083. .cf
  1084. .NP
  1085. The maximum number of parameters for a macro is 10 ($0-$9). 
  1086. The parameter(s) must be on the same line of the macro call. 
  1087. The parameters are separate by a non-alphanumeric character 
  1088. except '+' and '-' which
  1089. appear as the first character of the parameter line. If the 
  1090. first character is a alphanumeric character, then white space 
  1091. will be assumed as the delimiter. An example can be found 
  1092. above. If the require parameter(s) is/are not defined by the 
  1093. macro call, then the parameter(s) will be treated as null 
  1094. string.
  1095. .NP
  1096. There is another object formed and used somewhat
  1097. like a macro;  it is called a "diversion (file)" and is
  1098. useful for making lists such as references [footnotes] and
  1099. tables of contents.  A diversion is created or continued
  1100. with the commands: .DI [diversion] and .ED [end diversion].
  1101. A diversion can grow to be quite large and is, in fact, a
  1102. disk file.  To "regurgitate" the diversion file, its name
  1103. can be placed in the original command line, along with the
  1104. other input file names; alternatively, files can be
  1105. retrieved with the .SO ["source"] command.  The advantage
  1106. of using .SO is that inclusion can be accomplished without a
  1107. page break, nor even a line break between input files.  The
  1108.  .SO command is like a "CALL" or "GOSUB" in that there can be
  1109. nested .SO invokations; one can access a file with .SO that
  1110. contains in turn a .SO command, etc.  It is a limitation of
  1111. ROFF4 at present to not be able to handle the .so command
  1112. from keyboard input (it could be useful).  The files,
  1113. SOTEST, ONE, TWO, and THREE are provided to test and
  1114. demonstrate the .SO command.
  1115. .NP
  1116. All file names referenced by .di and .so are
  1117. automatically treated as uppercase.  The naming conventions
  1118. should conform to the operating system (CP/M).  It is a
  1119. limitation of the formatter at present to not realize that
  1120. "A:ZZ" would be the same as "ZZ"; be sure to use the same
  1121. form throughout!
  1122. .NP
  1123. We shall present a detailed example of the use  of
  1124. the above preprocessing commands to automate footnote and
  1125. reference numbering and collection.
  1126. .NP
  1127. We start by creating a register variable, "f#", to
  1128. keep track of the current footnote number:
  1129.  
  1130.  .rg f# 1
  1131. .NP
  1132. .cf !
  1133. We shall use, say, "[15]" as our means to display
  1134. reference numbering.  (We could have used superscripts
  1135. instead with "^+15^-"):
  1136. .sp
  1137. .cf
  1138.  .ds "fn"[\\f#]"
  1139.  
  1140. We have used "\\" so that "fn" is defined as "[\f#\] and
  1141. will be evaluated with the current footnote number at the
  1142. time of use (not of the time we nade this .ds definition).
  1143. By typing \fn\ we will get the reference in the form,
  1144. "[number]", that we wanted.
  1145. .NP
  1146. We want to create a diversion, "FNOTES", into which
  1147. we will place all our references.  The head of this file
  1148. will be titled with "REFERENCES":
  1149. .sp
  1150. .nf
  1151.  .di fnotes
  1152.  .ls 1
  1153.  .sp 1
  1154.  .ce 1
  1155.  REFERENCES
  1156.  .sp 2
  1157.  .ed
  1158. .fi
  1159. .NP
  1160. The diversion will contain (hopefully) a list of
  1161. numbered footnotes.  To make the addition of these footnotes
  1162. as painless as possible, we define two macros, "FS"
  1163. [footnote start] and "FE" [footnote end]:
  1164. .sp
  1165. .nf
  1166.  .dm FS
  1167.  .di fnotes
  1168.  .sp 1
  1169.  \\fn\\\\
  1170.  .em
  1171.          and:
  1172.  .dm FE
  1173.  .ed
  1174.  .rg f# +1
  1175.  .em
  1176.  
  1177. .fi
  1178. .NP
  1179. The FS macro skips a line and attaches the evaluation of
  1180. \fn\ to the start of the line that follows the macro during
  1181. execution.  The lines that follow the FS macro will be
  1182. diverted to FNOTES.  The FE macro terminates the diversion
  1183. and, also, increments the footnote number, f#.
  1184. .NP
  1185. We could try a very small piece of text now:
  1186.  
  1187. .nf
  1188.  .nf
  1189.  It is a nice day.\fn\
  1190.  .FS
  1191.  conventional expression.
  1192.  .FE
  1193.  It's a crummy day.\fn\
  1194.  .FS
  1195.  unconventional!
  1196.  .FE
  1197.  
  1198. The formatter will generate:
  1199.  
  1200.  It is a nice day.[1]
  1201.  It is a crummy day.[2]
  1202.  
  1203. and the diversion file, FNOTES, will contain:
  1204.  
  1205.  .ls 1
  1206.  .sp 1
  1207.  .ce 1
  1208.  REFERENCES
  1209.  .sp 2
  1210.  .sp 1
  1211.  [1]conventional expression.
  1212.  .sp 1
  1213.  [2]unconventional!
  1214.  
  1215. which, after formatting, will be:
  1216.  
  1217. .ls 1
  1218. .sp 1
  1219. .ce 1
  1220. REFERENCES
  1221. .sp 2
  1222. .sp 1
  1223. [1]conventional expression.
  1224. .sp 1
  1225. [2]unconventional!
  1226.  
  1227.